---
title: 标准化项目的 GitHub Flow 工作流
description: "在现代的开发过程中，GitHub Flow 已经成为一种非常流行的工作流程。本文将详细介绍 GitHub Flow 的流程以及在实际项目中如何应用它。"
date: "2024-11-07"
lang: zh
tags:
  - Github
  - 编程
category: 技术
cover: https://cdn.qladgk.com/images/20250508161829098.png
---

import Image from "@/components/mdx/Image";

<Image
  src="https://cdn.qladgk.com/images/20250508161829098.png"
  alt="cover"
  width={999}
  height={527}
  isArticleImage={true}
/>

import TIL from "@/components/mdx/TIL";

## 一、什么是 GitHub Flow？

当你使用版本控制系统 Git 的时候可能会将代码托管到 Github 等平台。为了方便多人协作，不让你的版本树乱七八糟，保证你的代码可以随时部署，更加规范化你的项目，通常都会使用一种 **workflow**。

而 GitHub Flow 是一种简单而高效的工作流程，主要依赖于 GitHub 上的 pull request 和分支机制来管理代码变更。[Github 文档](https://docs.github.com/zh/get-started/using-github/github-flow)

<Image
  src="https://cdn.qladgk.com/images/202411071409399.png"
  alt="Github Flow"
  width={999}
  height={527}
  isArticleImage={true}
/>

---

## 二、GitHub Flow 的核心步骤

GitHub Flow 的核心步骤非常简洁，通常包括以下几个步骤：

- 创建新分支（Create a branch）；
- 在新分支上完成开发并提交（Add commits）；
- 提交 Pull Request（Open a Pull Request）；
- 等待讨论审查（Discuss and review your code）；
- 部署发布（Deploy）；
- 完成合并（Merge）；

### 1、从 `main` 分支创建新的功能分支

在开始一个新的功能或修复一个 bug 时，从 `main` 分支创建一个独立的分支，不要直接修改 main 分支上的代码。

<Image
  src="https://cdn.qladgk.com/images/202411071419485.png"
  alt="本地分支"
  width={999}
  height={527}
  isArticleImage={true}
/>

这样保证主分支始终可部署，意味着你打算开发的部分都应该在自己的分支中工作，然后在它们准备好时重新合并到主分支中。

命名通常为 `feature/功能名称` 或 `fix/bug描述`，例如 `feature/add-user-auth`，这样能够方便大家了解分支的用途。

```bash
# 当前处在默认分支
git checkout main
git pull origin main
git checkout -b feature/add-user-auth
```

### 2、在独立分支中进行开发

在新的分支上进行开发，不会影响主分支的稳定性。期间可以自由提交和推送代码，也可以根据需要与团队成员协作。

<Image
  src="https://cdn.qladgk.com/images/202411071426035.png"
  alt="推送分支"
  width={999}
  height={527}
  isArticleImage={true}
/>

当你完成了这个功能的开发，你可以使用 git push 推送你的分支

```bash
# 当前处在独立分支 'feature/add-user-auth'
git add .
git commit -m "feat:Add user authentication feature"
git push origin feature/add-user-auth
```

**注意：提交日志的编写规范建议**

常见的类型包括：

| 类型         | 描述     | 举例                                                        |
| ------------ | -------- | ----------------------------------------------------------- |
| **feat**     | 添加功能 | feat: Add user authentication feature                       |
| **fix**      | 修复问题 | fix: Resolve issue where login button was not clickable     |
| **docs**     | 更新文档 | docs: Update README with setup instructions                 |
| **style**    | 改进样式 | style: Fix indentation and remove trailing spaces in app.js |
| **refactor** | 重构代码 | refactor: Simplify user authentication logic                |
| **perf**     | 性能优化 | perf: Improve image loading speed by using lazy loading     |
| **test**     | 修改测试 | test: Add unit tests for the authentication service         |
| **chore**    | 杂项任务 | chore: Update Node.js version in package.json               |

### 3、提交 Pull Request（PR）

<Image
  src="https://cdn.qladgk.com/images/202411071428080.png"
  alt="提交 PR"
  width={999}
  height={527}
  isArticleImage={true}
/>

当完成功能或 bug 修复后，向 `main` 分支发起 Pull Request。这个步骤是 GitHub Flow 的核心部分。在 PR 中，团队成员可以对代码进行审查，确保代码符合质量和项目规范，并且通过自动化测试来检查代码是否存在潜在问题。

<Image
  src="https://cdn.qladgk.com/images/202411071501284.png"
  alt="提交 PR"
  width={999}
  height={527}
  isArticleImage={true}
/>

在 PR 的标题和描述中，建议简要描述所实现的功能或修复的内容，并链接到相关的任务或 issue。

<Image
  src="https://cdn.qladgk.com/images/202411071504126.png"
  alt="PR 描述"
  width={999}
  height={527}
  isArticleImage={true}
/>

### 4、进行代码审查和测试

审查代码是团队合作中必不可少的一环。在 PR 提交之后，团队成员应检查代码是否符合编码规范、逻辑是否正确，并确认没有产生新的问题。

<Image
  src="https://cdn.qladgk.com/images/202411071429556.png"
  alt="代码审查"
  width={999}
  height={527}
  isArticleImage={true}
/>

- **代码审查**：通过团队成员之间的反馈，提升代码质量。
- **自动化测试**：在 PR 合并前确保代码经过充分测试。

### 5、提前触发部署

<Image
  src="https://cdn.qladgk.com/images/202411071441664.png"
  alt="部署"
  width={999}
  height={527}
  isArticleImage={true}
/>

在合并 PR 之前，代码可能已经部署到一个临时的 staging 环境或测试环境。通过这种方式，开发者可以确保代码在合并之前在一个接近生产的环境中运行，以发现潜在的问题。

<Image
  src="https://cdn.qladgk.com/images/202411071616818.png"
  alt="CI 工具"
  width={999}
  height={527}
  isArticleImage={true}
/>

https://github.com/marketplace?type=apps&category=continuous-integration

### 6、合并代码到 `main` 分支

通过代码审查和测试后，即可将 PR 合并到 `main` 分支。合并的操作可以在 GitHub 上直接完成，也可以通过命令行执行。

<Image
  src="https://cdn.qladgk.com/images/202411071431462.png"
  alt="代码合并"
  width={999}
  height={527}
  isArticleImage={true}
/>

- 在 GitHub 上点击 "Merge Pull Request" 按钮。

<Image
  src="https://cdn.qladgk.com/images/202411071628274.png"
  alt="Merge Pull Request"
  width={999}
  height={527}
  isArticleImage={true}
/>

为了保证 main 上的 commit 足够简洁，这里选择 Squash and merge，可以将功能分支上的提交合并成一次提交。

<Image
  src="https://cdn.qladgk.com/images/202411071631552.png"
  alt="Squash and merge"
  width={999}
  height={527}
  isArticleImage={true}
/>

合并完成之后，可以删除刚才的功能分支。

- 或使用命令行合并：

```bash
git checkout main
git merge feature/your-feature-name
git push origin main
```

---

## 三、提交日志的编写规范建议

### 1、遵循约定的提交信息格式

一个规范的提交日志应该包括三个主要部分：**标题**、**正文**和**页脚**。以下是一个常见的结构：

```md
<类型>: <简要描述>

<详细说明>

<关联的 issue 或任务 ID>
```

**示例：**

```md
feat: Add user authentication module

Implemented a new authentication system using JWT to allow users to log in
and register. This feature is crucial for securing user data and is part of
the sprint 3 goals.

Fixes #123 (login page issue)
```

更多标题示例见上文

### 2、避免模糊或无意义的提交信息

提交日志应该避免使用过于模糊或者无意义的描述，这会增加项目管理的困难。以下是一些不建议使用的示例：

| 原始日志内容           | 规范化后的提交日志                                   |
| ---------------------- | ---------------------------------------------------- |
| update code            | refactor: update core components for optimization    |
| fixed some bugs        | fix: resolve issue with user authentication flow     |
| working on new feature | feat: implement user profile management feature      |
| misc changes           | chore: update dependencies and improve code comments |

这类提交信息缺乏具体性，无法清楚表明做了什么变更，也不容易让其他开发人员理解你所做的工作。

### 3、避免一次提交过多内容

每次提交应该尽量聚焦于**单一目标**，避免把多个不相关的变更混在一起。通过将提交粒度控制在合适范围，可以使得后期的回溯和问题定位更加清晰。

这种提交同时涉及多个功能或问题，回溯时很难判断哪个部分引入了问题。应该分开为多个小的提交：

<TIL.DnD>
  <TIL.Dont>
    ```md {copy:false} {footer:false}
    fix: fix login issue, update readme, refactor header component

    ```

  </TIL.Dont>
  <TIL.Do>
    ```md {copy:false} {footer:false}
    fix: fix login issue
    docs: update readme for new login feature
    refactor: refactor header component
    ````
  </TIL.Do>
</TIL.DnD>
